home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 4 / Amiga Tools 4.iso / grafix / tools / xanim / xanim.readme < prev    next >
Text File  |  1995-05-07  |  35KB  |  887 lines

  1.  
  2. XAnim Rev 2.69.7.7  22Mar95
  3.  
  4. COMPILING ON UNIX Systems (And all Unix derivatives)
  5.  
  6.   If you have Imake on your system you can type
  7.  
  8.     xmkmf
  9.  
  10.   which should produce a Makefile from the Imakefile. Then
  11.   you can type:
  12.  
  13.     make xanim
  14.   
  15.   If this doesn't work you can copy Makefile.unx to Makefile.
  16.   Edit the Makefile and specify where the X11 includes and 
  17.   X11 libraries are on your particular machine. Then type
  18.  
  19.     make xanim
  20.  
  21.   NOTE: That in the Imakefile, XCOMM is used as a comment. This
  22.   is recommended by X11R6, but may break older revs. To fix,
  23.   simply replace every occurence of "XCOMM" with "#" in the
  24.   Imakefile. See top of Imakefile for more details.
  25.  
  26.  
  27. COMPILING ON VMS/AXP Systems
  28.   The files make.com and xanimXX.opt are provided for VMS users.
  29.   make.com should correctly detect wether you're running
  30.   DECWindows XUI or DECWindows MOTIF(revs 1.1 and 1.2) and use
  31.   the appropriate xanimXX.opt file.
  32.  
  33.   If you use the VMS MMS (or "make") facility, then a descript.mms
  34.   file is provided.
  35.  
  36.   NOTE: since VMS is case insensitve, all options to xanim must be
  37.   enclosed in double quotes in order for them to be proper recognized.
  38.   Example:
  39.         xanim "+bCn" anim1 anim2
  40.  
  41.  
  42. HOW TO USE XANIM
  43. The following is a copy of the man page with examples at the end.
  44.  
  45. SYNOPSIS
  46.      xanim [ +Vnum ] [ +Aaopts ]  [  +Ccopts  ]  [  +Ggopts  ]  [
  47.           +Mmopts  ] [ +Ssopts ] [ +Zzopts ] [ +opts ] animfile 
  48.           [ [ +opts ] [ animfile ] ... ]
  49.  
  50. DESCRIPTION
  51.      XAnim is a program that can display  animations  of  various
  52.      formats on systems running X11. XAnim currently supports the
  53.      following animation types:
  54.  
  55.       +  FLI animations.
  56.       +  FLC animations.
  57.       +  IFF animations.  The  following  features  are  sup-
  58.          ported:
  59.            -> Compressions 3,5,7,J(movies) and l(small L).
  60.            -> Color cycling during single images and anims.
  61.            -> Display Modes: depth 1-8, EHB, HAM and HAM8.
  62.       +  GIF87a and GIF89a files.
  63.            -> single and multiple images supported.
  64.            -> GIF89a animation extensions supported.
  65.       +  GIF89a animation extension support.
  66.       +  a kludgy text file listing gifs and  what  order  to
  67.          show them in.
  68.       +  DL animations. Formats 1, 2 and most of 3.
  69.       +  Amiga PFX(PageFlipper Plus F/X) animations. DISABLED TEMPORARILY.
  70.       +  Amiga MovieSetter animations(For those Eric Schwartz
  71.          fans).
  72.       +  Utah Raster Toolkit RLE images and anims.
  73.       +  AVI animations. Currently supported are
  74.            ->*IBM Ultimotion     (ULTI) depth 16.
  75.                -> JPEG               (JPEG) depth 24.
  76.                -> Motion JPEG        (MJPG) depth 24.
  77.                -> Intergraph JPEG    (IJPG) depth 24.
  78.            -> Microsoft Video 1  (CRAM) depth 8 and 16.
  79.            -> SuperMac Cinepak   (CVID) depth 24.
  80.            -> Uncompressed       (RGB ) depth 8
  81.            -> Uncompressed       (RGB ) depth 24
  82.            -> Run length encoded (RLE8) depth 8.
  83.            -> Editable MPEG      (XMPG) depth 24.
  84.       +  Quicktime Animations.  The  following  features  are
  85.          supported:
  86.                -> Uncompressed     (RAW ) depth 4,8,16,24 and 24+
  87.                -> Uncompressed     (RAW ) Gray depth 4 and 8.
  88.                -> Apple Graphics   (RLE ) depth 1,8,16 and 24.
  89.                -> Apple Graphics   (RLE ) GRAY depth 8.
  90.                -> Apple Animation  (SMC ) depth 8 and GRAY 8.
  91.                -> Apple Video      (RPZA) depth 16.
  92.                -> SuperMac Cinepak (CVID) depth 24 and GRAY 8.
  93.                -> Component Video  (YUV2) depth 24.
  94.                -> Photo JPEG       (JPEG) depth 8 and 24.
  95.                -> Supports multiple video trak's.
  96.                -> Supports animations with multiple codecs.
  97.                -> Supports merged and separated resource forks.
  98.       +  JFIF images. NOTE: use XV for single images. This is more
  99.          for animation of a sequence of JPEG images.
  100.           +  MPEG animations. Currently only Type  I  Frames  are
  101.              displayed.  Type  B  and Type P frames are currently
  102.              ignored, but will be added in future revs.
  103.       +  WAV audio files may have their sound added to any animation
  104.          type that doesn't already have audio, by specifying the .wav
  105.          file after the animation file on the command line. Currently
  106.          only the PCM audio codec is supported.
  107.       +  any combination of the above  on  the  same  command
  108.          line.
  109.  
  110. ---------------------------------------------------------------------------
  111. * The following copyright applies to all Ultimotion segments of the code:
  112.  
  113.   "Copyright International Business Machines Corporation 1994, All rights
  114.    reserved. This product uses Ultimotion(tm) IBM video technology."
  115. ---------------------------------------------------------------------------
  116.  
  117.      XAnim also provides various options that allow the  user  to
  118.      alter colormaps, playback speeds, looping modes and can pro-
  119.      vide on-the-fly scaling of animations with the mouse.
  120.  
  121. OPTIONS
  122.      A + will generally turn an option on and a -  will  turn  an
  123.      option  off.   This  can  be  reversed at compile time. (see
  124.      xanim_config.h).
  125.  
  126.      In each SubMenu, the options can be  run  together  with  no
  127.      intervening spaces. In the list of SubMenu options presented
  128.      below, the first letter given is the letter  that  specifies
  129.      the  SubMenu  and  should NOT be repeated if several SubMenu
  130.      options are to be run together.
  131.  
  132.      For example,  "+Cn  +Cs10  +CF4"  can  also  be  written  as
  133.      "+Cns10F4" or "+CF4s10n".
  134.  
  135.      A + or a - within a SubMenu will be an exit from  that  sub-
  136.      menu.   Options  will  affect  all  animations following the
  137.      invocation of that option. Some options may  be  changed  in
  138.      between animations without affecting previous animations.
  139.  
  140.      In the following sections,  an  "num"  represents  an  integer
  141.      number and an "fnum" represents a floating point number. Don't
  142.      include the double quotes. If a floating point number is of an 
  143.      integer amount, the "." need not be specified. There should be
  144.      no spaces between the option and the numbers.
  145.  
  146.      aopts SubMenu for Audio Options
  147.  
  148.       +Ae        Audio Enable. XAnim will ignore audio data if
  149.             this option is not used.
  150.  
  151.       +Ak        This option allows XAnim to skip video frames
  152.             in order to help keep video in sync with audio.
  153.             default is on.
  154.  
  155.       +As"fnum"    Scale Audio playback speed by "fnum". Only the
  156.             range 0.125 to 8.00 is allowed.
  157.             NOTE: CURRENTLY VIDEO DOESN'T SCALE WITH AUDIO.
  158.  
  159.       +Ap"num"    This turns a hardware specific Audio port on or off.
  160.                Port 0 - main speaker (on  by default)
  161.                Port 1 - headphones   (off by default)
  162.                Port 2 - line out     (off by default)
  163.  
  164.       +Av"num"    Sets the inital Audio Volume(0-100) with 0
  165.             the lowest. default is 40.
  166.  
  167.      copts SubMenu for Color Options
  168.  
  169.       +C1        Create a colormap from the  first  frame  of  a
  170.             TrueColor  anim  and  then  remap the remaining
  171.             frames to this colormap. This  can  potentially
  172.             add  significant time to the startup of an ani-
  173.             mation but usually results  in  better  colors.
  174.             The  animation  needs  to  be buffered for this
  175.             option to work.  Not  valid  for  TrueColor  or
  176.             DirectColor displays(nor is it needed).
  177.  
  178.       +C3        Convert TrueColor  anims  to  332(StaticColor).
  179.             TrueColor  anims  are  animations  that provide
  180.             separate RGB info for each pixel,  rather  than
  181.             each  pixel being an index into a global color-
  182.             map. AVI(16bit CRAM), QT(RPZA and RLE depth  16
  183.             and  24)  and URT RLE 24 bit anims are examples
  184.             of TrueColor anims. This option is ignored  for
  185.             TrueColor or DirectColor displays.
  186.  
  187.       +CA         Create  a  colormap  from  each  frame   of   a
  188.             TrueColor  anim.  This  can  be  useful  if the
  189.             colors radically change during  the  course  of
  190.             the  animation.  This can take a VERY,VERY long
  191.             time at start up. Animation must  be  buffered.
  192.             This   option   is  ignored  for  TrueColor  or
  193.             DirectColor displays.
  194.  
  195.       +Ca         Remap all images to  single  new  cmap  created
  196.             from all of the colormaps.
  197.  
  198.       +Cd         Use Floyd-Steinberg  dithering  if  needed  for
  199.             non-monochrome  displays.   This  will  cause a
  200.             reduction in playback speed.
  201.  
  202.       +Cf         Forcibly remap to all  frames  to  1st  frame's
  203.             cmap.
  204.  
  205.       +CF0          Turns off CF4 option.
  206.  
  207.       +CF4          This option samples the colors of true color
  208.             animations ahead of time and forms a color
  209.             lookup table.  Beats the just truncating to a
  210.             RGB 332 color table and IMHO beats dithering.
  211.             See the +s option below(also in copts submenu).
  212.             Currently ONLY Work with unbuffered animations
  213.  
  214.       +Cg         Convert TrueColor anims  to  gray  scale.  This
  215.             option is ignored for TrueColor and DirectColor
  216.             displays.
  217.  
  218.       +Ch         Use histogram to aid in color  reduction.  His-
  219.             trogramming  is  only  done  on frames that are
  220.             buffered.
  221.  
  222.       +Cm         This option is currently needed if you want  to
  223.             dither  TrueColor anims to a 332 colormap. Ani-
  224.             mation must be buffered.  Typically  +bC3dm  is
  225.             the  option  to  use. This can take a VERY long
  226.             time at start up.
  227.  
  228.       +Cn         Don't create new colormap but instead  allocate
  229.             colors from the X11 Display's default cmap.
  230.  
  231.       +Cs"num"    This is the number of frames the +CF4 option looks
  232.             at ahead of time. More frames potentially yields
  233.             better colors results, but takes more time at
  234.             start up.  default is 5.
  235.  
  236.      gopts SubMenu for Gamma Options
  237.  
  238.       +Ga"fnum"    Set gamma of animation to be displayed.
  239.  
  240.       +Gd"fnum"    Set gamma of display. 1.0 is no change. gamma's
  241.             greater  than 1.0 typically brighten the anima-
  242.             tion.
  243.  
  244.      mopts SubMenu for Median-Cut Quantization Options
  245.  
  246.       +Ma        compute box color from average of box.
  247.  
  248.       +Mc        compute box color as center of box.
  249.  
  250.       +Mb"num"    Truncate rgb to "num" bits before quantizing.
  251.  
  252.      sopts SubMenu for Scaling Options
  253.  
  254.       +Si        Half the  height  of  IFF  anims  if  they  are
  255.             interlaced.(Not  completely  reliable since not
  256.             all IFF anims correctly identify themselves  as
  257.             interlaced).
  258.  
  259.       +Sn        Prevents X11  window  from  resizing  to  match
  260.             animations's size.
  261.  
  262.       +Sr        Allow user to  resize  animation  on  the  fly.
  263.             Enlarging an animation can greatly reduce play-
  264.             back speed depending on the power of the cpu.
  265.  
  266.       +Ss"fnum"    Scale the size  of  animation  by  "fnum"  before
  267.             displaying.
  268.  
  269.       +Sh"fnum"    Scale the horizontal size of the  animation  by
  270.             "fnum" before displaying.
  271.  
  272.       +Sv"fnum"    Scale the vertical size  of  the  animation  by
  273.             "fnum" before displaying.
  274.  
  275.       +Sx"num"    Scale the animation to have  width  "num"  before
  276.             displaying.
  277.  
  278.       +Sy"num"    Scale the animation to have height  "num"  before
  279.             displaying.
  280.  
  281.       +Sc        Copy display scaling factors to display buffer-
  282.             ing factors.
  283.  
  284.       +SS"fnum"    Scale the size of the animation by "fnum"  before
  285.             buffering it.
  286.  
  287.       +SH"fnum"    Scale the horizontal size of the  animation  by
  288.             "fnum" before buffering it.
  289.  
  290.       +SV"fnum"    Scale the vertical size  of  the  animation  by
  291.             "fnum" before buffering it.
  292.  
  293.       +SX"num"    Scale the animation to have  width  "num"  before
  294.             buffering it.
  295.  
  296.       +SY"num"    Scale the animation to have height  "num"  before
  297.             buffering it.
  298.  
  299.       +SC        Copy buffer scaling factors to display  scaling
  300.             factors.
  301.  
  302.      zopts SubMenu for Special Options
  303.  
  304.  
  305.       +Ze        XAnim will exit after playing  through  command
  306.             line once.
  307.  
  308.       +Zp"num"    XAnim pause at frame "num" and then wait for user
  309.             input.  Several  pauses  may be specified. Each
  310.             group of pauses will only affect the  animation
  311.             immediately following them on the command line.
  312.             Pauses will occur at least once.
  313.  
  314.       +Zr        This option enables the Remote Control  Window.
  315.             This  overrides  the  default  condition set in
  316.             xanim_config.h. Remote Control support must  be
  317.             compiled into XAnim for this to work.
  318.  
  319.  
  320.      Normal Options
  321.  
  322.           +b        Uncompress and buffer images before displaying.
  323.             This  only  applies  to AVI, QT, IFF, FLI, FLC,
  324.             JPEG, MPEG and DL animations. The  rest(GIF87a,
  325.             GIF89a,  PFX  and  RLE)  are  currently  always
  326.             uncompressed and buffered. This is  cleared  by
  327.             the +f option.
  328.  
  329.       +B        Used X11 Shared Memory(if present)for unbuffered
  330.             animations only.(This is mutually exclusive with
  331.             +b above).
  332.  
  333.           +f        Don't load anim into memory, but read each sec-
  334.             tion  only  when needed. This is supported only
  335.             for AVI, QT, IFF, FLI, FLC, JPEG, MPEG  and  DL
  336.             animations.  This  option  is cleared by the +b
  337.             option.  This  saves  memory  at  the  cost  of
  338.             speed.
  339.  
  340.       +c        let xanim know that iff anim  is  a  nonlooping
  341.             one.
  342.  
  343.       +d"num"    debug switch. "num" can be from 0(off) to 5(most)
  344.             for level of detail.
  345.  
  346.       +F        Floyd-Steinberg dithering when needed.
  347.  
  348.       +j"num"    "num"  is  the  number  of  milliseconds  between
  349.             frames.  if  0  then  the time specified in the
  350.             animation is used for timing purposes.
  351.  
  352.       +l"num"    loop animation "num" number of times before  mov-
  353.             ing on to next animation.
  354.  
  355.       +lp"num"    ping-pong animation "num" number of times  before
  356.             moving on to next animation.
  357.  
  358.       +N        don't display images. Useful for benchmarking.
  359.  
  360.       +o        turns    on    certain    optimizations.    See
  361.             xanim.readme.
  362.  
  363.       +p        Use Pixmap instead of Image in X11. This option
  364.             has    no    effect   if   the   animation   is
  365.             buffered(either  by  default  or  with  the  +b
  366.             option).
  367.  
  368.       +r        Allow color cycling for IFF single images.
  369.  
  370.       +R        Allow color cycling  for  IFF  anims.  (default
  371.             should be off)
  372.  
  373.       +T0        Title option 0. Title is just XAnim.
  374.  
  375.       +T1        Title option 1. Title  is  current  anim  name.
  376.             When  anim is stopped, the current frame number
  377.             is included.
  378.  
  379.       +T2        Title option 2. Title is current anim name  and
  380.             current frame number.
  381.  
  382.       +v        Verbose mode. Gives some information about ani-
  383.             mation such as size, number of frames, etc.
  384.  
  385.       +V"num"    Select X11 Visual to use when displaying anima-
  386.             tion.  The  "num"  is  obtained  by  using the +X
  387.             option of xanim.
  388.  
  389.       +Vclass    Select the best X11 Visual of Class class  when
  390.             displaying  the  animation. class can be anyone
  391.             of the following strings and is  case  insensi-
  392.             tive. (ie StaTicGraY is same as staticgray).
  393.  
  394.             staticgray    Select best StaticGray Visual.
  395.             grayscale     Select best GrayScale Visual.
  396.             staticcolor   Select best StaticColor Visual.
  397.             pseudocolor   Select best PseudoColor Visual.
  398.             truecolor     Select best TrueColor Visual.
  399.             directcolor   Select best DirectColor Visual.
  400.  
  401.       +X        X11 verbose mode. Display information about the
  402.             support X11 visuals.
  403.  
  404.  
  405.  
  406.  
  407. WINDOW COMMANDS
  408.      Once the animation is up and running there are various  com-
  409.      mands  that  can  be entered into that animation window from
  410.      the keyboard.
  411.  
  412.      q         quit.
  413.  
  414.      Q         Quit.
  415.  
  416.      g         Stop color cycling.
  417.  
  418.      r         Restore original Colors(useful after g).
  419.  
  420.      w         Restore original window size(useful after resizing).
  421.  
  422.      z         This pops up or removes the Remote Control Window.
  423.                Remote Control support must be compiled into XAnim
  424.                for this to work.
  425.  
  426.      <space>   Toggle. starts/stops animation.
  427.  
  428.      ,         Single step back one frame.
  429.  
  430.      .         Single step forward one frame.
  431.  
  432.      <         Go back to start of previous anim.
  433.  
  434.      >         Go forward to start of next anim.
  435.  
  436.      m         Single step back one frame staying within anim.
  437.  
  438.      /         Single step forward one frame staying within anim.
  439.  
  440.      -         Increase animation playback speed.
  441.  
  442.      =         Decrease animation playback speed.
  443.  
  444.      0         Reset animation playback speed to original values.
  445.  
  446.      AUDIO RELATED WINDOW COMMANDS
  447.  
  448.      1           Decrement volume by 10.
  449.  
  450.      2           Decrement volume by 1.
  451.  
  452.      3           Increment volume by 1.
  453.  
  454.      4           Increment volume by 10.
  455.  
  456.      s           Toggle. Audio Volume(MUTE). on/off.
  457.  
  458.      8           Toggle. Main Speaker. on/off.
  459.  
  460.      9           Toggle. Headphones. on/off.
  461.  
  462.  
  463. MOUSE BUTTONS
  464.      Once the animation is up and running the mouse buttons  have
  465.      the following functions.
  466.  
  467.      <Left_Button>
  468.            Single step back one frame.
  469.  
  470.      <Middle_Button>
  471.            Toggle. starts/stops animation.
  472.  
  473.      <Right_Button>
  474.            Single step forward one frame.
  475.  
  476. BUFFERING, PIXMAPS and READ_FROM_FILE Options
  477.      XAnim by default will read the entire animation into memory.
  478.      PFX,  Moviesetter, GIF or URT RLE type animations are always
  479.      uncompressed and stored in memory as individual images.
  480.  
  481.      For the AVI, QT, IFF, FLI/FLC, JPEG, MPEG and DL animations,
  482.      only  the  compressed delta is stored. These deltas are then
  483.      uncompressed each time they need to be displayed. The buffer
  484.      option(+b)  may  be used to potentially speed up playback by
  485.      uncompressing and storing these images ahead  of  time.  But
  486.      more memory is used up in the process.
  487.  
  488.      When an XPutImage is called, the image typically gets copied
  489.      twice,  once to memory and then from there onto the display.
  490.      A pixmap is directly copied onto  the  display  without  the
  491.      first  copy.  This is why it is sometimes much faster to use
  492.      the pixmap option(+p).  Each image isn't  converted  into  a
  493.      pixmap until the first time it is displayed. This is why the
  494.      first loop of an animation using this  option  is  sometimes
  495.      slower  than  subsequent  loops. While the pixmap option may
  496.      improve playback speed, it will slow things down if  on-the-
  497.      fly  scaling needs to be performed. This is because XAnim no
  498.      longer has direct access to the image and  needs  to  get  a
  499.      copy of it before it can be scaled.
  500.  
  501.      The read from file option(+f) causes XAnim not to store  the
  502.      compressed  deltas in memory. Instead as each image is to be
  503.      displayed, XAnim reads the  corresponding  compressed  delta
  504.      from  the  file, expands it and then displays it. While this
  505.      can dramatically cut down on  memory  usage,  the  necessary
  506.      reads  from  disk(or whatever) can slow down playback speed.
  507.      XAnim still needs to allocate one  to  three  image  buffers
  508.      depending  on  the type of animation and the scaling options
  509.      used. This option is only supported for  AVI,  QT,  FLI/FLC,
  510.      IFF,  JPEG,  MPEG  and  DL animations. The BODY chunk of IFF
  511.      animations is not included in this. As a result, an IFF ani-
  512.      mation  that  is  made  up  of  several BODY chunks will not
  513.      currently benefit from this option.
  514.  
  515.  
  516. SCALING Options
  517.      There are two sets of scaling options. One set, the  display
  518.      scaling factors,  affects the size of the animation as it is
  519.      displayed. The other set, the buffer scaling factors, affect
  520.      the   size   of   the   images   as   they   are  stored  in
  521.      memory(buffered). The buffer  scaling  factors  only  affect
  522.      animations  that  are  buffered  and can greatly increase or
  523.      decrease memory usage.
  524.  
  525.      These two sets are completely independent of each other. You
  526.      can  set  the  buffer scaling factors to 20 times the normal
  527.      animation size and not affect the size at which that  anima-
  528.      tion  is  displayed.  The  images are stored at 20 times the
  529.      normal size(and at 400 times the memory usage), but then get
  530.      scaled  back  down  to  normal  size before being displayed.
  531.      NOTE: that an animation must be buffered in  order  for  the
  532.      buffer scaling factors to have any affect on it. The display
  533.      scaling factors affect all animations.
  534.  
  535.      You can create pixellation like  affects  by  buffering  the
  536.      animation  at  1/8 it's normal size, but keeping the display
  537.      scaling factors at the original size. (IE  "xanim  +bSS0.125
  538.      anim.anim").
  539.  
  540.      Many times it's faster to store  and  display  an  animation
  541.      with large dimensions at half-size. The option "+bSS0.5C" or
  542.      "+bSS0.5s0.5" both will accomplish this. To save memory, you
  543.      could  even store the animation at half size and yet display
  544.      it at full size. "+bSS0.5" will accomplish this.
  545.  
  546. FORWARDS, BACKWARDS and OPTIMIZATION.
  547.      Many type of animations(FLI/FLC/IFF/some AVI  and  QTs)  are
  548.      compressed  with  forward  playback in mind only. Each delta
  549.      only stores the difference between the current frame and the
  550.      previous frame. As a results, most of these animations don't
  551.      display correctly when played backwards.  Even when buffered
  552.      up, these may not work, since XAnim only stores the smallest
  553.      rectangle that encompasses the  changes  from  the  previous
  554.      frame.  You  can  force  XAnim  to store the entire frame by
  555.      specifying the "-o" option to turn  this  optimization  off.
  556.      This will most likely use more memory and slow down the ani-
  557.      mation, since more of the image needs to  be  stored  and/or
  558.      displayed.
  559.  
  560. COLOR OPTIONS
  561.      Most of this will be a TBD for a future rev and what's  here
  562.      might be sketchy, incomplete or just plain confusing.
  563.  
  564.      TrueColor and DirectColor displays don't need to worry about
  565.      most of these options, as the animations can be displayed in
  566.      their original colors(ignoring monitor variations etc). How-
  567.      ever,  TrueColor  and  DirectColor  displays  can't  display
  568.  
  569.      animations that employ color cycling  techniques  where  the
  570.      colormap  changes  from  frame  to frame.  DirectColor could
  571.      potentially support this, but not TrueColor.
  572.  
  573.      For the rest of the displays, the problem  becomes  matching
  574.      the  colors in the animations to the available colors of the
  575.      Display.  For  most  PseudoColor  displays  this  means  256
  576.      colors.  Many  of  which are already in use by various other
  577.      programs. XAnim defaults to creating it's own  colormap  and
  578.      using  all  the  colors  from  that. The window manager then
  579.      installs this new colormap, whenever the  mouse  pointer  is
  580.      inside  the  XAnim  animation  window(Sometimes  a  specific
  581.      action is required to change the ColorMap Focus, like click-
  582.      ing  in the window or pressing a specific key). In any case,
  583.      this action usually causes  all  the  other  colors  on  the
  584.      screen  to  be  temporarily  "messed-up"  until the mouse is
  585.      moved out of the animation window. The  alternative,  is  to
  586.      use  the  "+Cn"  option.  Now XAnim tries allocating all the
  587.      colors it needs from the current colormap. If it can't get a
  588.      certain color, then XAnim choose one that is "close" to this
  589.      certain color. Close is completely arbitrary. The  animation
  590.      is  now displayed in colors that are different than the ori-
  591.      ginal colors. This difference may or may not be noticeable.
  592.  
  593.      Another big problem is when the animations are what I called
  594.      TrueColor animations. Where each pixel is stored as RGB tri-
  595.      plets. For example, AVI 16 bit CRAM animations.  Each  pixel
  596.      has  5  bits of Red, 5 bits of Green and 5 bits of Blue info
  597.      associated with it. This means there  can  be  up  to  32768
  598.      unique  colors  in  each  image.  And  on  most  PseudoColor
  599.      displays we can only display 256 unique colors. Beside  get-
  600.      ting  better  displays,  what  can  we do? XAnim defaults to
  601.      truncating the RGB information from 555 to 332. That is to 3
  602.      bits  of  Red,  3  bits of Green and 2 bits of Blue. Less on
  603.      Blue because the human eye is  more  sensitive  to  Red  and
  604.      Green than Blue.  This 332 colormap happens to be 256 colors
  605.      in size, which nicely fits  in  with  our  display.  If  our
  606.      display  only  had  64 colors, then XAnim is smart enough to
  607.      truncate things down to 222. Now the problem is  the  colors
  608.      of the displayed anim are noticeably different than the ori-
  609.      ginal colors.  Typically you  can  see  color  banding  etc.
  610.      While  this  is fine to get a feel for the animation, we can
  611.      do better. One of the solutions XAnim  currently  offers  is
  612.      the "+bC1" option. What this does is choose the the best 256
  613.      colors from the first image  of  the  animation.  Then  each
  614.      pixel  of  each subsequent image is remapped to one of these
  615.      256 colors.  This takes up some CPU time up front  and  more
  616.      memory since each image needs to be buffered, but results in
  617.      a colors that are closer to the originals.  Another  option,
  618.      "+bCA",  chooses  the  best  256  from  each image, then 256
  619.      colors from all these colormaps  are  chosen  as  the  final
  620.      colormap.   This  is useful if the colors in the first image
  621.      aren't representative of the rest of the animation. This can
  622.      be  very  slow.  Another  option  that is supported, but not
  623.      really optimized for yet is "+bC3dm". This causes  XAnim  to
  624.      use  a  332 colormap and then apply a Floyd-Steinberg dither
  625.      algorithm to each image.  Currently this is very slow.  Dif-
  626.      ferent  dithers(like Ordered) and better optimizations might
  627.      speed this up  in  future  revs.  In  general,  handling  of
  628.      TrueColor animations in XAnim needs to be improved.
  629.  
  630.      Another scenario where colors need to be remapped,  is  when
  631.      several  images  or animations with different colormaps need
  632.      to be displayed.  Changing the colormap usually  results  in
  633.      an annoying flicker. One solution to this is to remap all of
  634.      the images/animations to the same colormap. The "+Ca" option
  635.      chooses  the  best  colors  from  all the colormaps and then
  636.      remaps all the images to it. The "+Cf" option, simply remaps
  637.      everything  to the first colormap.  The "+Ch" option is use-
  638.      ful when an animation's colormap specifies a lot  of  colors
  639.      that aren't used. XAnim looks through each buffered image of
  640.      the animation and makes a histogram of the  useage  of  each
  641.      color.  This  information  is then used to weedout unused or
  642.      rarely used colors.
  643.  
  644. QUICKTIME ANIMATIONS
  645.      Quicktime animations are  usually  stored  in  two  separate
  646.      files.  One is call a data fork and ends with a ".data". The
  647.      other is a resource fork and ends in  a  ".rsrc".  Sometimes
  648.      these  animations  are in a "flattened/merged fork" format, 
  649.      where everything is put into one file. There's no standard 
  650.      naming  format for these types of files although usually 
  651.      .qt or .mov is used.
  652.  
  653.      For example, if you have a quicktime animation  made  up  of
  654.      two  files  named:  "spin.rsrc"  and  "spin.data",   you can
  655.      display them using Xanim with either of the  following  com-
  656.      mands  "xanim  spin"  or  "xanim spin.rsrc".  XAnim is smart
  657.      enough to add/modfiy the  ".rsrc"  and  ".data"  endings  as
  658.      needed.
  659.  
  660.      If you use AUFS from the Columbia  Appletalk  Package,  then
  661.      Macintosh  files have their data fork stored in the expected
  662.      place, and the resource fork is in a file with the same name
  663.      in a  .resource subdirectory. Therefore, if the data fork is
  664.      in "spin", and the resource fork isin  ".resource/spin", the
  665.      movie can be displayed with "xanim spin".
  666.  
  667.      For "flattened/merged fork" quicktime animations, you  need
  668.      to  specify the entire file name.
  669.  
  670.      NOTE: XAnim doesn't support 100% of the quicktime format.
  671.  
  672. EXAMPLES:
  673.     To display a single animation with Audio:
  674.  
  675.         xanim +Ae car_race.avi
  676.  
  677.     To display a audio animation on Sparc. main speakers off
  678.     and  headphones on:
  679.  
  680.         xanim +Aep1 -Ap0 car_race.avi
  681.  
  682.     To display a single animation:
  683.  
  684.         xanim iff3.anim
  685.  
  686.     To display a nonlooping IFF animation:
  687.  
  688.         xanim +c iff3.anim
  689.  
  690.     To display A.fli 3 times, B.anim and C.movie 2 times each and D.fli
  691.     once before repeating:
  692.  
  693.         xanim -l3 A.fli -l2 B.anim C.movie -l1 D.fli
  694.  
  695.     To see A.anim real slow(2 seconds for each frame):
  696.  
  697.         xanim +j2000 A.anim
  698.  
  699.     To display title image for a while then run an animation at
  700.     normal speed:
  701.  
  702.         xanim +j2000 title.gif +j0 anim.gifanim
  703.  
  704.  
  705. A series of GIF's can be displayed as:
  706.  
  707.     xanim im_0.gif im_1.gif im_2.gif ... im_36.gif
  708.  
  709.  or
  710.  
  711.     xanim im_*.gif
  712.  
  713.  or
  714.  
  715.     xanim im.txt
  716.  
  717.  or
  718.  
  719.     xanim im.gifanim
  720.  
  721. where im.txt is a txt file(a list of images, see anim.doc for more details).
  722. and im.gifanim is one gif file composed of im_0.gif through im_36.gif.
  723. (see txtmerge to create a single gif file from a txt file).
  724.  
  725. X11 Notes:
  726. --------------------------------------
  727.  I. X11 Server Options
  728.  
  729.    When XAnim opens the display it passes the argument list to X11 which
  730.    then filters off the arguments it recognizes. XAnim won't even see these
  731.    arguments(which is sometimes a problem). For instance
  732.  
  733.    xa -geom =+100+100 skier.fli
  734.  
  735.    will play the anim skier.fli at pos <100,100> on the X11 screen.  Or
  736.  
  737.    xa -display nantucket:0.0 skier.fli
  738.  
  739.    will display the anim skier.fli on the machine nantucket's display.
  740.  
  741.    Sometimes this is a problem, because a valid XAnim option is stripped by the
  742.    X11 server. For instance if +r was being stripped, then use ++r instead.
  743.    Same goes with -r. Use --r instead if you believe it's being filtered
  744.    by X11.
  745.  
  746. Machine Specific and Compiler Notes:
  747. --------------------------------------
  748.  Some PC's need you to uncomment the line below in Makefile.
  749.  #XA_INET_LIB = -linet
  750.  
  751.  Depending on your window manager(mwm,uwm,olwm,twm etc), you might
  752.  want to have XAnim do a XInstallColormap. This shouldn't be necessary
  753.  for most workstations and can cause core dumps on some PCs.
  754.  There are usually user selectable options for each window manager
  755.  that selects the colormap focus policy(pointer,fixed,explicit etc).
  756.  Use -DNO_INSTALL in Makefile if you DON't want XAnim to install
  757.  the colormap.
  758.  
  759.  Some X11's don't have support for multiple visuals.  An executable
  760.  compiled with such an X11 will not be able to correctly run on a
  761.  machine that does supports multiple visuals even if they're binary
  762.  compatible.
  763.  
  764.  Hugh D.R. Evans has supplied make.com, xanim.opt and added VMS defines
  765.  so that VMS users may compile and run XAnim. Rick Dyson has provided
  766.  the descript.mms file and some VMS fixes. John Kneitz has also
  767.  provide some VMS fixes and suggestions.
  768.  
  769. And Yet More Notes about Quicktime Animations
  770. ---------------------------------------------
  771.         NOTES ON QUICKTIME ANIMATIONS WITH XANIM
  772.  
  773.   (these are just my notes and may contain some inconsistencies.
  774.    There's currently some question about the true meaning of
  775.    "flatten". It might just mean taking a quicktime file and
  776.    replacing a references to another files with those files
  777.    themselves.  But lately many people use it to mean collapsing
  778.    the *.data and *.rsrc forks into one *.data fork for export
  779.    to a non-mac computer. - Mark)
  780.  
  781.  
  782.    EXTRACTING Quicktime Animations
  783.  
  784.     Typically you will obtain the quicktime animations that have
  785.     been archived and then binhex'd. If the file you have ends
  786.     in a .hqx, then you need to run hexbin on it ("hexbin anim.hqx").
  787.     This will create a *.bin file(not necessarily anim.bin, it
  788.     could be anything.bin. The actual name is contained within
  789.     the *.hqx file).  
  790.  
  791.     If the file you have ends in a .bin or you've just hexbin'd a file, 
  792.     now you need to unpack it. In other words extract the files that
  793.     are contained within it. These files can be programs/documents/
  794.     animations/images etc. They're not necessarily quicktime animations.
  795.  
  796.     There is a program called macunpack that should be used to
  797.     accomplish this. You need to use the -f option, I recommend
  798.     the -lv options as well. (ie "macunpack -flv file.bin")
  799.  
  800.     Macunpack doesn't support certain DiskDoubler or Stuffit Deluxe
  801.     archives. There is no unix/pc program that I know of that does(except 
  802.     for the Mac). In this case your only choice is to get a hold of a 
  803.     Macintosh computer and someone who knows how to use it and
  804.     hopefully some method of transferring files to/from it.
  805.  
  806.     Once you've unpacked everything, you should have three files,
  807.     a *.info, a *.rsrc and a *.data. You can delete the *.info file.
  808.     XAnim doesn't need or use it.
  809.  
  810.     The quicktime animation is made up of BOTH the *.rsrc and the
  811.     *.data files and therefore XAnim needs BOTH the *.rsrc and the 
  812.     *.data in order to recognize and display the animation.
  813.   
  814.     The only exception to this is if the animation has been "flattened".
  815.     Essentially, all that this means is that the .rsrc and .data files
  816.     were merged into one file for export to a non-mac computer.
  817.     This file doesn't have any real naming conventions, but it is
  818.     usually something like .mov, .mv, .qt, etc(it is never .bin or .hqx). 
  819.     And it is rarely .data. If XAnim can't play it, then it's 95%
  820.     likely to be a *.data fork(that's missing a *.rsrc fork) and not
  821.     a flattened quicktime animation.
  822.  
  823.     Macunpack and hexbin can be found in the macutil archive. They
  824.     are available at the following locations:
  825.  
  826.         sumex-aim.stanford.edu:/info-mac/unix/macutil-20b1.shar
  827.         ftp.cwi.nl:/pub/macutil2.0b3.shar.Z
  828.         solaris.ims.ac.jp:/pub/unix/mac/macutil-20b1.shar
  829.  
  830.     Use archie to find other sites.
  831.  
  832.     Here's a quick blurb on macutils from the readme.
  833.  
  834.             o hexbin - a program to convert BinHex 4.0 to MacBinary;
  835.           it also converts uuencode (and UULite) files to their
  836.           native binary format; support for .dl, .hex, and .hcx
  837.           formats (all predecessors of BinHex 4.0) also exists
  838.  
  839.             o macunpack - a program to unpack PackIt, StuffIt,
  840.           Diamond, Compactor/Compact Pro, most StuffIt Classic
  841.           and StuffIt Deluxe, DiskDoubler, Zoom and LHarc/MacLHa
  842.           archives.
  843.  
  844.           It also decodes BinHex 5.0, MacBinary, uuencode, and
  845.           UNIX compress (ie: .Z suffix) files (as well as variants
  846.           of compress implemented by various Macintosh compress
  847.           programs).
  848.  
  849.  
  850.   TRANSFERING DIRECTLY FROM A MACINTOSH
  851.  
  852.     If you are transferring a quicktime animation directly from a 
  853.     Macintosh(ftp/fetch/gator/etc), you need to use the MacBinary mode.
  854.     This will archive all three resource forks(.info,.rsrc and .data) 
  855.     into a .bin file and transfer that. You must then use "macunpack -flv"
  856.     as described above.
  857.   
  858.     If you use Binary mode(as opposed to the MacBinary mode), ONLY the 
  859.     *.data file will be transferred. This *.data file is useless without
  860.     the *.rsrc file, unless it happens to be "flattened". If you don't
  861.     absolutely know this to be true, then use the MacBinary mode and 
  862.     extract with macunpack.
  863.  
  864.  
  865.   OTHER PROGRAMS
  866.  
  867.     mcvert is also capable of extracting the *.rsrc and *.data files
  868.     form a MacBinary file(*.bin). It doesn't support all of the
  869.     archival compression formats that macunpack does and I'm not
  870.     as familiar with it. Archie should be able to find it.
  871.  
  872.   CREATING A QUICKTIME FOR EXPORT ON A MACINTOSH
  873.  
  874.     Movieconverter, part of Apple's Quicktime Starter Kit (a commercial product)
  875.     can do this.  Save the movie as BOTH "Make self-contained" and "Playable
  876.     on non-Apple computers." 
  877.  
  878.  
  879.   If you have any other questions or problems trying to run 
  880.   quicktime animation using xanim I might be able to answer
  881.   them.
  882.  
  883. ------------------------------------------------------------------------------
  884.  
  885. Mark Podlipec - podlipec@wellfleet.com or podlipec@shell.portal.com
  886. http://www.portal.com/~podlipec/home.html  "The XAnim Home Page"
  887.